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OS-9 INTERACTIVE DEBUGGER 
Debug Commands 



MEMORY COMMANDS 



The interactive debugger has two memory-related commands to 
display large blocks of memory^ and to clear and test memory. 



Clear and Test Memory Command 

The command C followed by TWO expressions simultaneously 
performs a "walking bit" memory test and clears all memory 
between the two evaluated addresses. The first expression gives 
the starting address^ and the second the ending address (which 
must be higher). If any byte{s) fail the testr its address is 
displayed c Of course ^ only RAM memory can be tested and 
cleared. 

WARNING: THIS COMMAND CAN BE DANGEROUS FOR OBVIOUS REASONS. BE 
SURE OP WHAT MEMORY YOU ARE CLEARING. 

Examples 

DBS C 1200 15PP 
DBS C . .+256 



Dump Memory Command 

The M command y which is also followed by two addresses ^ 
displays a screen-sized display of memory contents in tabular 
formr in both hexadecimal and ASCII form* The starting address 
of each line is printed on the left^ followed by the contents of 
the 16 subsequent memory locations . On the far right is the 
ASCII representation of the same memory locations. Those 
locations containing non-displayable characters have periods in 
their place. The high order bit is ignored for the display of 
the ascii character. 



Search Memory Command 

The "S" command is used to search an area of memory for a 
one- or two--byte pattern. The search begins at the present Dot 
address « The "S" is followed by two expressions s the first 
expression is the ending address of the search^ and the second 
expression is the data to be searched for. If this value is 
less than 256 a one-byte comparison is used^ otherwise two bytes 
are compared. If a matching pattern is found in memory r Dot is 
set to the address where it was located (which is displayed) . 
If no match occurred^ another "DBs" prompt is displayed. 
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INTRODUCTION 

The Microware Interactive Debugger is a powerful tool for 
system diagnostics or testing 6809 machine language programs* 
It is also useful when you need to directly access the 
computer's memory for any of a number of reasons: testing I/O 
interfaces y verifying data^ etc. The calculator mode can 
simplify computation of addresses, radix conversion, and other 
mathematical problems often encountered by machine-language 
programmers* 



Basic Concepts 

The debugger operates in response to single line commands 
typed in from the keyboard* You can tell when you are "talking 
to" the debugger because it always displays a "DB:" prompt when 
it expects a command line* 

Each line is terminated by a carriage return ("new line" on 
some keyboards). If you make a mistake while typing, you can use 
the backspace key (control H) , or delete the entire line using 
the control-X key. 

Each command line starts with a single character command 
which may be followed by text, or one or two arithmetic 
expressions, depending on the specific command. Opper-case and 
lower-case character can be used interchangeably. Here's an 
example of the "space" command which displays the result of an 
expression in hexadecimal and decimal notation: 



DB : A+2 

$000C #00012 

DB: 



Numbers entered into or displayed by the debugger are in 
hexadecimal notation, unless special commands are used, such as 
the decimal conversion command shown above. Two important topics 
must be covered before beginninq the command descriptions 
themselves; expression syntax and DOT. 
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EXPRESSIONS 



A powerful capability of the Interactive Debugger is its 
integral expression interpreter r which permits you to type in 
full expressions wherever an input number is called for in a 
commands Expressions used by the Interactive Debugger are 
similar to those used with high-level languages such as BASIC, 
except there are some extra operators and operands that are 
unique to the debugger. 

Numbers used in expressions are 16 bit unsigned integers r 
which is the 6809 *s "native" arithmetic representation. The 
allowable range of numbers is therefore zero to 65535. Two's 
complement addition and subtraction is performed correctly, but 
will print out as large positive numbers in decimal 
representations. Some commands require byte values and an 
error message will be given if the result of the expression is 
too large to be stored in a byte ( > 255 ) . Also, some operands 
are only a byte long (such as individual memory locations and 
some registers). These are automatically converted to 16-bit 
"words" without sign extension. Spaces may be used between 
operators and operands as desired to improve readability but do 
not atfect evaluation. 



Constants 



Constants can be in base 2 ("binary"), base 10 ("decimal"), 
or base 16 (hexadecimal or "hex"). Binary and decimal constants 
require a prefix characters % (binary) or #(decimal). All other 
numbers are assumed to be hex. Hex numbers may also have an 
optional $ prefix. Here are some examples: 

DECIMAL HEXADECIMAL BINARY 



#100 64 $64 %1100100 

#255 FF $PP %11111111 

#6000 1770 $1770 %1011101110000 

#65535 FFFF $FFFF %1111111111111111 

Character constants may also be used. A single quote ' for one 
character constants and a double quote " for two-character 
constants. These produce the numerical value of the ASCII codes 
for the character (s) which follow. For example: 



*A = $0041 

^0 = $0030 

"AB = $4142 

"99 = $3939 
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Special Names 

There are other legal operands in expressions; Dot^ Dot-Dot , 
and register names* 

Dot is simply the debugger's current working address in 
memory. It can be examined, changedr updated, used in 
expressions or recalled. It has the main effect of eliminating a 
tremendous amount of memory address typing. The following debug 
command prints the current working address: 

DB: • 

2204 82 



Dot-Dot is the previous value of Dot, if it was changed. The 
following debug command prints the previous value of Dots 

DBS .. 

0500 12 



Register Names 

MPD Registers may be specified by a colon character "s" followed 
by the mnemonic name of the register; for example: 



sA Accumulator A 

sB Accumumator B 

sD Double Accumulator 

sX X Register 

sY Y Register 

sO U Register 

sDP Direct Page Register 

sSP Stack Pointer 

sPC Program Counter 

sCC Condition Codes Register 



The values returned are of the program under test's registers, 
which are "stacked" when the debugger is active. Those 
registers which are a single byte long are promoted to a word 
when used in expressions. 

NOTE: When a program is interrupted by a break point, the SP 
will be pointing at the bottom of the MPO register stack. 



(C) 1980, 1981, 1982 MICROWARE SYSTEMS CORPORATION 

Page 2-2 



OS- 9 INTERACTIVE DEBUGGER 
Expressions 



Operators 



Operators indicate arithmetic or logical operations. The 
operators having a higher precedence are executed before those 
having lower precedence. For exampler all multiplications are 
performed before additions. Operators in a single expression 
having equal precedence are evaluated left to right. 
Parentheses may be used to override precedence as desired. Here 
are the operators^ in precedence order from weaker to stronger: 



+ addition 

* muliplication 

& logical AND 

- nega 



- subtraction 
/ division 
1 logical OR 
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DEBUG COMMANDS 



Calculator Command 

To use the calculator command, enter a line starting with one or 
more spaces followed by any legal expression, then "return". 
The expression is evaluated and the result is displayed on the 
following line in both hexadecimal and decimal representations. 

Here are some examples: 

DB: 5000+200 

$5200 #20992 

DB: 8800/2 

$4400 #17408 

DB: #100+#12 

$0070 #00112 

These commands are also handy for converting values from one 
representation to another: 

DB: %11110000 

$00F0 #00240 
DB: 'A 

$0041 #00065 
DB: #100 

$00C4 #00100 

You can also use indirect addressing to look at memory without 
changing Dot: 

DB: <.> 

$004P #00079 

Another trick is simulating 6809 indexed or indexed indirect 
instructions. For example: 

DB: [:D+:Y] 

is the same as the assembly language syntax [D,Y]. 
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Memory Examine 



Several commands relate directly to Dot, For example, typing 
just causes the current value of Dot and the contents of 

that memory address to be displayed^ for example: 

DB: . 

2201 BO 

DB: 

The first number r 2201^ is the present value of Dotf and BO is 
the contents of memory location 2201/ Typing a line with 
nothing (just a return) increments Dot and prints its new value 
and contents. This is how to "step through" sequential memory 
locations: 

DB: 

2202 05 

DB: 

2203 C2 

DB: 

2204 82 



The minus sign is the opposite: it decrements Dot and prints its 
value and contents: 

DB: . 

2204 82 
DB: — 

2203 C2 

DB: 

2202 05 



To change the value of Dotr you type a period^ followed by an 
expression^ which is evaluated and becomes the new value for 
Dot: 



DB: . 500 
0500 12 



Memory Change 



To change the contents of the memory location pointed to by Dot, 
you type an equal sign followed by an expression. The expression 
is evaluated f and the result stored at Dot, which is then 
incremented and the next address/contents are displayed. The 
memory location is checked after the new value is stored to make 
sure it actually changed to the correct value. If it didn't, an 
error message is displayed. This will happen when an attempt is 
made to alter non-RAM memory. In particular, many 6800-family 
interface devices (such as PlASf ACIAs, etc.) have registers 
that will not read the same as when written to. 
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DB: . 

2203 C2 
DB: =FF 

2204 01 
DB: - 

2203 FF 

DB: 

One additional feature: whenever Dot is changed, its last value 
is saved, and can be restored by typing two periods: 

DB: . 

1000 23 
DB: . 2000 

2000 9C 
DB: . . 

1000 23 



REGISTER COMMANDS 

Several £orms of the register command can be used to examine 
one or all registers, or to change a specific register's 
contents. A word about registers: the registers accessed are 
"images" of register values on a stack. When the debugger is 
first entered, an initial stack is automatically set up for the 
user. The register images on this stack are passed to the 
program under test the first time the "G" command is used. The 
registers are also valid after breakpoints are encountered and 
are passed back to the program upon the n^xt "G" command. 

IMPORTANT NOTE ABOUT CHANGING REGISTER CONTENTS: 



1. IP YOU CHANGE THE SP REGISTER, YOU WILL MOVE YOUR STACK 
AND THE OTHER REGISTER CONTENTS WILL CHANGE. 

2. BIT 7 OF THE CC REGISTER (THE E FLAG) MUST ALWAYS BE SET 
FOR THE G COMMAND TO WORK. IF YOU FORGET, THE DEBUGGER 
WILL NOT RETURN TO THE PROGRAM CORRECTLY. 
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Displaying Registers 

To display the contents of a specific register ^ enter a colon 
followed by the register name. The Debugger will respond by 
displaying the current register contents in hex. Examples: 

DB: :PC 

C499 
DB: :B 

007E 
DB: :SP 

42FD 

To display all registers f type ":", then hit return. The 
debugger responds by, displaying the register names with their 
corresponding hex contents beneath. 

DB: : 

SP CC A B DP X Y 0 PC 
C499 C4 20 IC 01 DD3E 239A 0000 240C 



Changing Register Contents 

To assign a new value to a register ^ type the register name 
followed by an expression. The expression is evaluated and 
stored in the register specified. When 8-bit ' registers are 
named, the expression given must have a value that fits in a 
single byte f or an error message is displayed and the register 
is not changed. 

Here are some examples: 

DB: :X #4096 

DB: :DP 0 

DB: :D 24CP+:y 
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Breakpoint Commands 

The breakpoint capabilities of the debugger allow you to 
specify addresses where execution of the program under test is 
to be suspended f and the debugger re-entered. When a breakpoint 
is encountered^ the values of the MPU registers and the "DB:" 
prompt will be displayed meaning the debugger is ready to accept 
a command. Registers can be examined or changed ^ memory can be 
altered^ etc. Breakpoints may be inserted at up to 12 different 
addresses. 

Breakpoints are implemented by using the 6809 SWI 
instruction^ which when executed ^ interrupts the program and 
saves its complete state on the stack. The SWI instructions are 
automatically inserted and removed by the debugger at the right 
times so you will not "see" them in memory. Because the SWIs 
operate by temporarily replacing an instruction opcode ^ there 
are three restrictions on their use: 

1. Breakpoints cannot be used in programs in ROM. 

2. Breakpoints must be located in the first (opcode) byte 
of the instruction. 

3. User programs cannot utilize the SWI instruction for 
other purposes (but CAN use SWI2 and SWIS) 

When the breakpoint is encountered during execution of the 
program under test^ the debugger is reentered and the program's 
register contents are displayed using the same format as the 
"display register" command. 



Setting Breakpoints 
Display Breakpoints 

The B command is used to insert a breakpoint if followed by 
an expression^ or to display all present breakpoint addresses if 
given without an expression. 

DB: B ICOO 
DB: B 4FD3 
DB: . 

1277 39 

DB: B . 

DB: B 

ICOO 4PD3 1277 

DB : 
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Remove Breakpoint 

The K command removes ("Kills") a breakpoint at a specific 
address if followed by an expression^ or ALL (caution!) 
breakpoints if used alone. 

DB: B 

ICOO 4PD3 1277 
DB: K 4PD3 
DB: B 

ICOO 1277 
DB: K 
DB: B 

DB: 



GO - RESUME PROGRAM EXECUTION 

The G ("Go") command is used to resume program execution after a 
breakpoint/If a breakpoint exists at the present program 
counter addresSf that breakpoint is not inserted so that it is 
not immediately re-executed • A loop must have at least two 
breakpoints in it if execution is to be suspended each time 
through the loop* 

Note that the "E" command is usually used before the first 
"G" command to set up the program to be tested. As mentioned 
previouslyf the Interactive Debugger initially sets up a default 
stack so the command: 

G expression 

can be used to start a program at the address the expression 
evaluates to. 

Here are some examples: 

DB: G 4C00 
DB: G :PC+100 
DB: G [•] 
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OS- 9 RELATED COMMANDS 



SHELL COMMAND 

This command calls the shell to execute one or more system 
command lines. Its format is a dollar sign optionally followed 
by a shell command line. If the command line is givenr the 
shell will execute just that line and return back to the 
debugger. If the dollar sign is immediately followed by an end- 
of-line, the shell will print prompts for one or more command 
lines in its usual manner. You can return to the (undisturbed) 
debugger by typing an end-of-f ile character (usually ESCAPE) • 

This command is useful for calling the system utility 
programs and the Interactive Assembler from within the debugger. 

DBS $dir 

DBr $unlink mypgm; mdir e; load tests 
DBs $asm myprogram o«myprogram 



QUIT COMMAND 

This command (Q) causes the Interactive debugger to execute a 
EXIT system call which normally kills it and notifies its parent 
process. This generally returns you to the program that you were 
previously executing (typically the Shell) . 

Examples 

DB: Q 

0S9% 



EXECUTE COMMAND 

The Execute Command (E followed by a text line) performs the 
rough equivalent of the CHAIN system command r except instead of 
starting the new program (and overlaying the Interactive 
Debugger itself ) ^ it sets up its stack and all the debugger 
commands operate on the new program (G starts it) . Note that 
this command will allocate program and data area memory as 
appropriate. The new program uses the debugger's current 
standard I/O paths ^ but can open other paths as necessary. In 
effect r the debugger and the program become coroutines. 
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This command is acknowlegec3 by a register dump showing the 
program's initial register values. The "G" command is used to 
begin actual program execution. 

The "E" command will set up the MPU registers as if you had just 
performed an P$CHAN service request as shown below: 



high + + <~ y 

parameter 
area 

+ — < — X, SP 



data area 



low 



+ 

! direct page ! 
„ — ^+ < — 0^ DP 



D « Parameter area size 
PC « Module entry point absolute address 
CC = (P«0)> (I«0) 



Example: 



DB: E myprogram 

SP CC A B DP X Y PC 
0CP3 C8 00 01 OC OCPP ODOO 9214 

DB: 



LINK COMMAND 

This command (L followed by text) attempts to link to the module 
who's name is given in the text line. If successful> Dot is set 
to the address of the first byte of the program and is 
displayed* 



Example: 

DB: L PPMATH 
ECOO 87 

DB: 



(C) 1980 r 1981, 1982 MICROWARE SYSTEMS CORPORATION 

Page 4-2 



OS- 9 INTERACTIVE DEBUGGER USERS MANUAL 
Using the Debugger with a Real Program 



USING THE DEBUGGER WITH A REAL PROGRAM 



The example program shown below is presented here to show how 
the various debug commands may be used with a real program. 
This program prints "HELLO WORLD" and then waits for a line of 
input; 

NAM EXAMPLE 
OPT Or-M 

USE /D0/DEPS/OS9DEFS 

* 0S-»9 System Definition File Included 
* 









opt 


1 




0000 






ORG 


0 




0000 




LINLEN 


RMB 


2 


LINE LENGTH 


0002 




INPBDF 


RMB 


80 


LINE INPUT BUFFER 


0052 






RMB 


150 


HARDWARE STACK 


00E7 




STACK 


EQU 


.-1 




0OE8 




DATMEM 


EQU 


• 


DATA AREA MEMORY SIZE 


0000 


87CD0047 




MOD 


ENDPGM, NAME 


r $ 11 r $ 81 , ENTRY , DATMEM 


OOOD 


4558414D 


NAME 


FCS 


/EXAMPLE/ 


MODULE NAME STRING 


0014 




ENTRY 


EQU 


* 


MODULE ENTRY POINT 


0014 


308D0020 




LE2^ 


OUTSTR,PCR 


OUTPUT STRING ADDRESS 


0018 


108E000C 




LDY 


#STRLEN 


GET STRING LENGTH 


OOlC 


8601 




LDA 


#1 


STANDARD OUTPUT PATH 


OOIE 


103F8C 




0S9 


I$WRLN 


WRITE THE LINE 


0021 


2512 




BCS 


ERROR 


BRA IF ANY ERRORS 


0023 


3042 




LEAK 


INPBUF,U 


ADDR OF INPUT BUFFER 


0025 


108E0050 




LDY 


#80 


MAX OF 80 CHARACTERS 


0029 


8600 




LDA 


#0 


STANDARD INPUT PATH 


002B 


103F8B 




0S9 


I$RDLN 


READ THE LINE 


002E 


2505 




BCS 


ERROR 


BRA IF ANY I/O ERRORS 


0030 


109F00 




STY 


LINLEN 


SAVE THE LINE LENGTH 


0033 


C600 




LDB 


#0 


RETURN WITH NO ERRORS 


0035 


103F06 


ERROR 


0S9 


P$EXIT 


TERMINATE THE PROCESS 


0038 


48454C4C 


OOTSTR 


PCC 


/HELLO WORLD/ OUTPUT STRING 


0043 


OD 




PCB 


$0D 


END OF LINE CHARACTER 


COOC 




STRLEN 


EQU 


♦-OUTSTR 


STRING LENGTH 


0044 


268A06 




EMOD 




END OF MODULE 


0047 




ENDPGM 


EQU 


* 


END OF PROGRAM 
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A Session With The Debugger 

Below is an example of how DEBUG might be used on the program 
above. DEBUG is called from OS-9, the $ command is used to tell 
SHELL to load "EXAMPLE" into memory, the "L" command is used to 
link to it, etc. 

0S9: DEBUG #2K 

Interactive Debugger 
DB: $LOAD /Dl/EXAMPLE 
DB: L EXAMPLE 
9200 87 

DB: . 

9200 87 
DB: M . .+44 

9200 87CD 0047 OOOD 1181 9300 1400 E845 5841 . . .D EXA 

9210 4D50 4CC5 308D 0020 108E OOOC 8601 103P MPL.O. ? 

9220 8C25 1230 4210 8E00 5086 0010 3F8B 2505 .% .OB. . .P. . .?.% . 

9230 109P 00C6 0010 3P06 4845 4C4C 4F20 574F .?. HELLO WO 

9240 524C 440D A484 7P8D D4A6 A02A P639 3432 RLD *.942 

DB: E EXAMPLE 

SP CC A B DP X Y U PC 
0DF3 C8 00 01 OD ODPP OEOO ODOO 9214 

DB: . 

9200 87 
DB: B ,+2E 

DB: G * 
HELLO WORLD 
hello computer 

BKPT: 

SP CC A B DP X Y U PC 
0DF3 CO 00 01 OD 0D02 OOOP ODOO 922E 
DB: M :U :U+20 

ODOO PA31 6865 6C6C 6F20 636F 6D70 7574 6572 .Ihello computer 

ODIO ODDF COOS E9P1 95PA 4C0D IDFA 0AC4 5900 L.....Y. 

0D2O 0B64 360B CPBl 0091 P820 5AE2 5AP8 5AP8 .d6 Z.Z.Z. 



DB: 


. :U+2 




0D02 


68 


DB: 








0D03 


65 


DB: 








0DO4 


6C 


DB: 








0D05 


6C 


DB: 


Q 




0S9 


• 
• 





(C) 1980, 1981, 1982 MICROWARE SYSTEMS CORPORATION 

Page 5-2 



OS-9 INTERACTIVE DEBUGGER 
Debugger Command Summary 



INTERACTIVE DEBUGGER COMMAND SUMMARY 



Calculator Command - - 3-1 

(SP) expr Evaluate; display result in hex and decimal - - 3-1 

Dot Commands - - 3-2 

Print Dot address and contents -------- 3-2 

Restore last DOT^ print address and contents - 3-3 

. expr Set Dot to result , print address and contents - 3-2 

= expr Set memory at Dot to result ---------- 3-2 

Backup Dotf print address and contents - - - - 3-2 

(CR) Move Dot forward/ print address and contents - 3-2 

Breakpoint Commands 3-5 

B Display all breakpoints - ----------- 3-5 

B expr Set breakpoint at result address ------- 3-5 

K Kill all breakpoints 3^5 

K expr Kill breakpoint at result address ------- 3-6 

G Go to program ----------------- 3-6 

G expr Go to program at result address -------- 3-6 

Memory Commands - - - - — ^ - - - - - - - - - - - - - - - - - 3-7 

M exprl expr2 Tabular display of memory (dump) ------ 3-7 

C exprl expr 2 Clear and test memory ----------- 3-7 

S exprl expr2 Search memory for pattern --------- 3-7 

Register Commands --------------------- 3-3 

2 Display all register contents -------- 3-4 

rreg Display specific register contents ------ 3-4 

sreg expr Set register to result ------------ 3-4 

GS-9 Related Commands ------------------- 4-1 

$ text Call OS-9 shell - - ^ - « 4-1 

L text Link to module named , print address ------ 4-2 

Q Quit debugging 4-1 

E text Prepare for execution ------------- 4-1 
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ERROR REPORTING 



The Interactive Debugger will detect several types of errors 
which cause an error message and code number to be displayed • 
The error codes are always displayed in decimal notation. The 
various codes and descriptions are listed below. Error codes 
other than those listed are standard OS-9 error codes returned 
by various system calls* 



0 ILLEGAL CONSTANT: The expression included a constant that 
had an illegal character or was too large ( > 65535 ) . 

1 DIVIDE BY ZERO: A division was attempted using a divisor of 
zerOc 

2 MULTIPLICATION OVERFLOW: the product of the multiplication 
was greater then 65535 

3 OPERAND MISSING: An operator was not followed by a legal 
operand. 

4 RIGHT PARENTHESIS MISSSING: misnested parentheses 

5 RIGHT BRACKET MISSING: misnested brackets 

6 RIGHT CARAT MISSING: misnested byte-- indirect ( < and > ) 

7 INCORRECT REGISTER: misspelled^ missing or^ illegal 
register name followed the colon. 

8 BYTE OVERFLOW: attempted to store a value greater than 
255 in a byte-sized destination. 

9 COMMAND ERROR: misspelled ^ missing or illegal command. 

10 NO CHANGE: the memory location did not match the value 
assigned to it. 

11 BREAKPOINT TABLE FULL: the maximum number of twelve 
breakpoints already exist. 

12 BREAKPOINT NOT POUND: no breakpoint exists at the address 
given. 

13 ILLEGAL SWI: A SWI instruction was encountered in the 
user program at an address other than a breakpoint. 
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